Inside Macintosh: Programming With JManager /

Chapter 1 - Using JManager

Creating an AWT Context

On the Mac OS, an AWT context is defined by a JMAWTContextRef object. Every Java program running within a session has its own AWT context. You can create an AWT context before or after instantiating a locator for the applet you want to run, but you must instantiate the AWT context before instantiating the applet.

To instantiate a JMAWTContextRef object, you call the JMNewAWTContext function (page 62) as shown in Listing 1-6. You must have already instantiated a session before creating an AWT context.

Listing 1-6 Creating an AWT context

/* define callbacks for the AWT context */
JMAWTContextCallbacks sessionCallbacks = {
   kJMVersion,          /* should be kJMVersion */
   MyRequestFrame,      /* callback to create a frame */
   MyReleaseFrame,      /* callback to release a frame */
   MyUniqueMenuID,      /* callback to give the AWT a valid MenuID */
   MyExceptionOccurred, /* notify that an exception occurred */
   };

/* create an AWT context for this applet */
JMAWTContextRef context;
err = JMNewAWTContext(&context, theSession, &sessionCallbacks, 0);

/* if all went well, then start the context */
if (err == noErr) {
   err = JMResumeAWTContext(context);
   }

The value context references the JMAWTContext object, and you should pass this value in other JManager functions to specify this particular context. When first instantiated, the AWT context is in a stopped state; to start the context, you must call the function JMResumeAWTContext (page 64).

You must specify a number of callbacks when calling JMNewAWTContext. JManager uses these callbacks to handle requests from the Java program for new frames (that is, windows). The MyRequestFrame callback (page 99) creates a new window, MyReleaseFrame releases a window (page 100), and MyUniqueMenuID creates a new menu ID (page 101). For example, if the Java program requests that a frame be made available, the application-defined callback function MyRequestFrame should request a new Mac OS window. Listing 1-7 shows an example of such a function.

Listing 1-7 Application-defined new frame function

OSStatus MyRequestFrame(JMAWTContextRef context, JMFrameRef newFrame,
   JMFrameKind kind, UInt32 width, UInt32 height, Boolean resizeable,
   JMFrameCallbacks* callbacks)
{
   static int xOff = 30, yOff = 40;
   WindowPtr win;
   Rect bounds;
   
   /* callbacks with pointers to your implementation-- */
   /* note that you also fill in the version number that you */
   /* compiled against (based on what you passed to JMOpenSession) */ 

   callbacks->fVersion = kJMVersion;
   callbacks->fSetupPort = MySetupPort;
   callbacks->fRestorePort = MyRestorePort;
   callbacks->fResizeRequest = MyResizeRequest;
   callbacks->fInvalRect = MyInvalRect;
   callbacks->fShowHide = MyShowHide;
   callbacks->fSetTitle = MySetTitle;
   callbacks->fCheckUpdate = MyCheckUpdate;
   
   bounds.left = xOff;
   xOff += 10;
   bounds.right = bounds.left + width;
   bounds.top = yOff;
   yOff += 10;
   bounds.bottom = bounds.top + height;
   
   win = NewCWindow(nil, &bounds, "\p", false, documentProc, 
      (WindowPtr) -1, true, (long) newFrame);
   if (win == nil)
      return memFullErr;

   /* note that the window isn't visible now--it will be made */
   /* visible through a callback */

   return JMSetFrameData(newFrame, (JMClientData) win);
}

The MyRequestFrame function calls the Mac OS Toolbox function NewCWindow to request a window that corresponds to the frame. This example always creates a window of type documentProc (a simple document window without size or zoom boxes), but you can select different window types depending on the kind parameter passed into the callback function. See "Frame Types" (page 42) for a listing of possible requests.

The function MyRequestFrame also requires a number of callback functions that allow the Java program to manipulate the new window (for example, to show, hide, or update the window). For more information on these functions, see "Displaying Frames" (page 18) and "Application-Defined Functions" (page 97).

As part of the NewCWindow call, the reference to the frame (as held in newFrame) is stored in the refCon field of the window record (a WindowRecord structure). Doing so allows you to determine the frame associated with a window by simply calling the Mac OS Toolbox function GetWRefCon.

In a similar fashion, the JMSetFrameData function is used to store a pointer to the new window record in the frame's client data. You can then easily determine the window associated with a given frame by using a function such as in Listing 1-8.

Listing 1-8 Determining the window associated with a frame

WindowPtr getFrameWindow(JMFrameRef frame)
{
   if (frame) {
      WindowPtr win = nil;
      if (JMGetFrameData(frame, (JMClientData*) &win) == noErr)
         return win;
   }
   return nil;
}

---

Subtopics

Displaying Frames

Getting Information About AWT Contexts and Frames

Removing an AWT Context